home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 April: Mac OS SDK / Dev.CD Apr 96 SDK / Dev.CD Apr 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / Documentation / Tech Notes & Articles / Recipes / Standards / ODByteArray < prev    next >
Encoding:
Text File  |  1995-07-11  |  2.6 KB  |  90 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Recipes
  2.  
  3. ODByteArray
  4. By The OpenDoc Design Team
  5. July 11, 1995
  6.  
  7. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  8. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  9. Mac and OpenDoc are trademarks of Apple Computer, Inc.
  10.  
  11. Changes since DR2
  12.  
  13. 1) Fixed parameter passing errors with SetValue and GetValue.
  14.  
  15. ODByteArray
  16.  
  17. What is an ODByteArray?
  18.  
  19. An ODByteArray is defined as a sequence of octets:
  20.  
  21. typedef struct {
  22.     unsigned long _maximum;
  23.     unsigned long _length;
  24.     octet *_buffer;
  25. } _IDL_SEQUENCE_octet;
  26. typedef _IDL_SEQUENCE_octet ODByteArray;
  27.  
  28. _length is the number of bytes of relevant data.
  29. _maximum is the number of bytes in the buffer.
  30. _buffer is the pointer to the memory block containing the data.
  31.  
  32. Some rules about ODByteArray:
  33. 1) _length must be smaller or equal to _maximum.
  34. 2) kODNULL cannot be passed to any parameter which expects an ODByteArray pointer.
  35. 3) _buffer must be allocated by ODNewPtr or equivalent SOM functions.
  36.  
  37. Why do we need ODByteArray?
  38.  
  39. The original OpenDoc API accepted and returned buffer pointers and their corresponding sizes. However, the API has been updated to use ODByteArray. This renders the OpenDoc API CORBA compliant and ready for distribution.
  40.  
  41. Usage example:
  42.  
  43. The following examples creates ODByteArray on the stack. There is no restriction that ODByteArray is a stack variable. It can be allocated in the heap.
  44.  
  45. 1) Setting a value on a storage unit with a pre-allocated buffer (ptr and size):
  46.  
  47. // Allocate the byte array on the stack
  48. ODByteArray ba; 
  49.  
  50. // Set up the byte array
  51. ba._length = size;
  52. ba._maximum = size;
  53. ba._buffer = ptr;
  54.  
  55. // Get the value
  56. su->SetValue(ev, &ba);
  57.  
  58. // ba will be deallocated automatically when the function exits.
  59. // ptr needs to be explicitly deallocated by client.
  60.  
  61. 2) Getting a value from a storage unit:
  62.  
  63. // Allocate the byte array on the stack. The fields are not pre-filled.
  64. ODByteArray ba; 
  65.  
  66. // Get the value
  67. ODULong length = su->GetValue(ev, desiredLength, &ba);
  68.  
  69. // Use the buffer.
  70. SomeFunction(ba._buffer);
  71.  
  72. // ba will be deallocated automatically when the function exits.
  73. // ptr needs to be explicitly deallocated by client.
  74. ODDisposePtr(ba._buffer);
  75.  
  76. 3) Getting a return value which is an ODByteArray:
  77.  
  78. // Byte array is allocated on the stack. None of the fields in the ODByteArray needs to
  79. // be set prior to use.
  80. ODByteArray ba = container->GetID(ev);
  81.  
  82. // Use the buffer in the ODByteArray.
  83. ......
  84.  
  85. // Deallocate the buffer.
  86. // Note that even though the client of the method does not allocate the memory, it is the
  87. // client’s responsibility to deallocate it.
  88. ODDisposePtr(ba._buffer);
  89.  
  90. // Byte Array is deallocated from the stack when the function exits.